第三部分：参数篇
5. JSON 配置文件参数详解
本章节详细列出了 covnert_model 工具在各个核心阶段（导入、量化、推理、导出）所使用的参数。
5.1 模型导入 (Import)
目标：此为工具链的第一步，旨在将一个由主流框架（如 TensorFlow、ONNX、Caffe）训练生成的模型，解析并转换为 taNNTC 工具链专用的中间表示 (IR) 格式。
输入：原始模型文件（例如 .onnx、.pb、.tflite 文件）。
输出：一个 .json 文件（描述网络结构）和一个 .data 文件（存储网络权重）。这对文件是后续所有操作的基础。
在 import 字段支持下列参数配置：
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
name | 模型通用名称，用于命名输出文件 | str | model | "name": "yolo11s" |
framework | 导入模型的原框架 | ONNX / Caffe / TensorFlow /... | — | "framework": "ONNX" |
inputs | 模型输入节点名（空格分隔多个） | str list | 框架可自动识别时可省略 | "inputs": "images" |
input-size-list | 各输入张量形状，多个输入间用 # 分隔 | str | 自动推断（支持时） | "input-size-list": "1,3,640,640" |
outputs | 模型输出节点名（空格分隔多个） | str list | 自动识别（支持时） | "outputs": "out0 out1 out2" |
onnx_model | (ONNX) 待导入的源模型文件路径 | str | — | "onnx_model": "./yolo11s.onnx" |
input-dtype-list | (ONNX) 各输入数据类型 | float/int8/uint8/int16/… | float | "input-dtype-list": "float" |
proto | (Caffe) 待导入的模型文件协议 | caffe / lstm_caffe / ... | — | "proto": "caffe" |
caffemodel | (Caffe) .caffemodel 文件路径 | str | — | "caffemodel": "mobilenet.caffemodel" |
protobuf_file | (TensorFlow) .pb 模型文件路径 | str | — | "protobuf_file": "frozen_graph.pb" |
mean_values | (TensorFlow) 输入均值 | float[,float...] | — | "mean_values": "0.0,0.0,0.0" |
std_values | (TensorFlow) 输入标准差 | float[,float...] | — | "std_values": "255.0,255.0,255.0" |
predef_file | (TensorFlow) 预定义 .npz（占位符/阶段开关等） | str | — | "predef_file": "flags.npz" |
subgraphs | (TensorFlow) 指定子图的输入/输出列表 | str | — | "subgraphs": "in1#out1;in2#out2" |
tflite_file | (TFLite) .tflite 模型文件路径 | str | — | "tflite_file": "mobilenet.tflite" |
cfg_file | (Darknet) .cfg 模型文件路径 | str | — | "cfg_file": "yolo.cfg |
weights_file | (Darknet) .weights 文件路径 | str | — | "weights_file": yolo.weights |
pytorch_file | (PyTorch) .pt 模型文件路径 | str | — | "pytorch_file": "alexnet.pt" |
config | (PyTorch) 导入配置文件路径（pytorch 框架专用） | str | — | "config": "import_cfg.json" |
keras_file | (Keras) .h5 模型文件路径 | str | — | "keras_file": "mobilenet.h5" |
5.2 前后处理配置文件的参数说明
yml 文件用法：工具会基于已导入的模型结构（.json 文件），自动生成预处理和后处理配置文件的模板（.yml 文件），用户只需根据模型所需，修改少量参数或不作修改。可以直接修改 .yml 文件，再进行模型导出(convert_model export)，也可以在 .json 文件中配置要修改的参数。
目前 preprocess 字段支持的参数如下，工具会根据此字段参数修改 model_inputmeta.yml 文件：
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
reverse_channel | 翻转输入 tensor 的通道顺序 | bool | false | "reverse_channel": true |
mean | 预处理中归一化使用的均值 (值域[0,1]) | arr | — | "mean": [0, 0, 0] |
std | 预处理中归一化使用的std值 (值域[0,1]) | arr | — | "std": [1.0, 1.0, 1.0] |
scale | 预处理中归一化使用的scale值 | float | — | "scale": 0.00392156 |
add_preprocess_node | 向导出的网络添加前处理节点 | bool | false | "add_preprocess_node": false |
目前 postprocess 字段支持的参数如下，工具会根据此字段参数修改 postprocess.yml 文件：
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
add_postprocess_node | 是否向导出的网络添加后处理节点 | bool | false | "add_postprocess_node": false |
premute | 指定维度顺序，重新排列输出张量的维度 | arr | — | "permute": [0,1,2,3] |
float32_out | 将输出张量转换为 float32 数据类型 | false | — | "float32_out": false |
5.2.1 *_inputmeta.yml 前处理配置文件内容详解
此文件用于配置模型输入端的预处理。
-
常见配置：
mean、scale：设置归一化的均值和缩放系数。reverse_channel：BGR 与 RGB 通道反转开关。工具链将图片解码后按 RGB 顺序输入网络。如果目标网络默认的 channel 顺序是 BGR，则此处需要将此项设为true。若不需要反转通道，则设为false。
-
高级用法（指定输入格式）：如果希望模型直接接收
RGB_PACKED或NV12等特定硬件格式的数据，并让 NPU 执行预处理，需要修改：add_preproc_node: true
preproc_type: IMAGE_NV12 # (或其他格式)
5.2.2 *_postprocess_file.yml 后处理配置文件内容详解
此文件用于配置模型输出端的后处理。
-
常见用法（强制输出为 Float32）：默认情况下，模型输出的数据类型与量化类型一致。如果希望无论量化类型是什么，最终输出都是 Float32，需要对每个输出层进行如下配置：
postprocess:
app_postprocs: # 该部分配置会影响最终导出的模型
- lid: output_0 # 替换为您的输出层名称
postproc_params:
add_postproc_node: true
force_float32: true # 强制输出为 float32
# 如果有多个输出层，在此继续添加
- lid: output_1
postproc_params:
# ...
5.3 模型量化 (Quantize)
目标：此为关键的优化步骤，旨在通过降低模型的数据精度（例如从 FP32 转换为 INT8），来减小模型体积、降低内存占用，并利用 NPU 的定点运算单元实现显著的推理加速。
输入：上一阶段生成的 .json 和 .data 文件，以及一个用于校准的样本数据集。
输出：一个 .quantize 文件，其中包含了每一层的量化参数（如缩放因子、零点等）。
在 quantize 字段支持下列参数配置：
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
qtype | 目标精度类型 | uint8 / int8 / int16 / bfloat16 / float16 / … | uint8 | "qtype": "uint8" |
dataset_file_type | 描述数据集文件的类型 | TEXT / NPY | TEXT | "dataset_file_type":"TEXT" |
dataset_file | 量化数据集列表文件（每行一张图片路径） | str | — | "dataset_file": "./dataset.txt" |
input_num | 校准次数 | int | 1 | "input_num": 25 |
5.4 模型导出 (Export)
目标：此为工具链的最后一步，旨在将中间表示 (IR) 和量化结果，编译并打包成一个专为目标 NPU 硬件优化、可直接部署执行的最终产物。
输入：.json、.data 文件以及（若为量化模型）.quantize 文件。
输出：一个或多个可直接在板端运行的文件，最核心的是统一的二进制图文件（例如 .nb）。
在 export 字段支持下列参数配置：
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
core_number | 目标硬件上的核心使用数量 | 1 / 2 | — | "core_number": 1 |
5.5 模型推理 (Inference)
目标：此模块使用 pegasus 命令行工具，用于在 开发主机（PC/服务器） 上模拟模型的推理过程，主要用于功能验证和精度评估。您可以在部署到硬件之前，用它来快速验证原始浮点模型的正确性，或评估量化后模型的精度损失情况。
输入：.json 和 .data 文件，（若评估量化模型）还需 .quantize 文件。
输出：模型的推理结果，可用于与基准值 (Golden) 进行比对。
| 参数 | 含义 | 类型 / 可选值 | 默认值 | 示例 |
|---|---|---|---|---|
--model | 推理用 .json | str | — | --model y11.json |
--model-data | 推理用 .data | str | — | --model-data y11.data |
--model-quantize | 推理用 .quantize（选择量化推理时） | str | — | --model-quantize y11.quantize |
--with-input-meta | 输入元数据 .yml | str | — | --with-input-meta inputmeta.yml |
--dtype | 推理精度 | float32 / quantized | float32 | --dtype quantized |
--batch-size | 推理批大小 | int | 由输入元数据推断 | --batch-size 1 |
--iterations | 推理批次数 | int | 1 | --iterations 100 |
--device | 推理计算设备 | GPU/CPU | GPU | --device GPU |
--postprocess | 内置后处理任务 | print_topn / dump_result / classification_validate / detection_validate / … | classification_classic | --postprocess detection_validate |
--postprocess-file | 自定义后处理 .yml | str | — | --postprocess-file post.yml |
--output-dir | 推理结果输出目录 | str | 当前目录/控制台 | --output-dir outputs/ |